@vulfram/engine 0.5.6-alpha

package/src/engine/world/entities.ts

@@ -0,0 +1,516 @@
+import type { ShadowConfig } from '../../types/cmds/shadow';
+import type { EnvironmentConfig } from '../../types/cmds/environment';
+import type { NotificationLevel, UserAttentionType } from '../../types/kinds';
+import { getWorldOrThrow, requireInitialized } from '../bridge/guards';
+import type {
+  CameraProps,
+  CreateWindowProps,
+  GeometryProps,
+  InputStateComponent,
+  Intent,
+  LightProps,
+  MaterialProps,
+  ModelProps,
+  TagProps,
+  TextureProps,
+  TransformProps,
+  WindowProps,
+  WindowStateComponent,
+} from '../ecs';
+import { engineState } from '../state';
+
+/**
+ * Emits an intent to the specified world.
+ * Intents are processed by systems at the beginning of each tick.
+ */
+export function emitIntent(worldId: number, intent: Intent): void {
+  requireInitialized();
+  const world = getWorldOrThrow(worldId);
+  world.pendingIntents.push(intent);
+}
+
+/**
+ * Emits an intent to create a window in the core.
+ */
+export function createWindow(worldId: number, props: CreateWindowProps): void {
+  emitIntent(worldId, {
+    type: 'create-window',
+    props,
+  });
+}
+
+/**
+ * Emits an intent to close the window associated with this world.
+ */
+export function closeWindow(worldId: number): void {
+  emitIntent(worldId, {
+    type: 'close-window',
+  });
+}
+
+/**
+ * Updates window properties.
+ */
+export function updateWindow(worldId: number, props: WindowProps): void {
+  emitIntent(worldId, {
+    type: 'update-window',
+    props,
+  });
+}
+
+/**
+ * Requests user attention for the window.
+ */
+export function requestAttention(
+  worldId: number,
+  attentionType?: UserAttentionType,
+): void {
+  emitIntent(worldId, {
+    type: 'request-attention',
+    attentionType,
+  });
+}
+
+/**
+ * Focuses the window.
+ */
+export function focusWindow(worldId: number): void {
+  emitIntent(worldId, {
+    type: 'focus-window',
+  });
+}
+
+/**
+ * Requests a list of resources from the engine for debugging.
+ */
+export function requestResourceList(
+  worldId: number,
+  resourceType:
+    | 'model'
+    | 'material'
+    | 'texture'
+    | 'geometry'
+    | 'light'
+    | 'camera',
+): void {
+  emitIntent(worldId, {
+    type: 'request-resource-list',
+    resourceType,
+  });
+}
+
+/**
+ * Disposes a material.
+ */
+export function disposeMaterial(worldId: number, resourceId: number): void {
+  emitIntent(worldId, { type: 'dispose-material', resourceId });
+}
+
+/**
+ * Disposes a texture.
+ */
+export function disposeTexture(worldId: number, resourceId: number): void {
+  emitIntent(worldId, { type: 'dispose-texture', resourceId });
+}
+
+/**
+ * Disposes a geometry.
+ */
+export function disposeGeometry(worldId: number, resourceId: number): void {
+  emitIntent(worldId, { type: 'dispose-geometry', resourceId });
+}
+
+/**
+ * Sends a system notification.
+ */
+export function sendNotification(
+  worldId: number,
+  props: {
+    level: NotificationLevel;
+    title: string;
+    message: string;
+  },
+): void {
+  emitIntent(worldId, {
+    type: 'send-notification',
+    level: props.level,
+    title: props.title,
+    message: props.message,
+  });
+}
+
+/**
+ * Configures shadow settings for the world.
+ */
+export function configureShadows(worldId: number, config: ShadowConfig): void {
+  emitIntent(worldId, {
+    type: 'configure-shadows',
+    config,
+  });
+}
+
+/**
+ * Configures environment settings for the world.
+ */
+export function configureEnvironment(
+  worldId: number,
+  config: EnvironmentConfig,
+): void {
+  emitIntent(worldId, {
+    type: 'configure-environment',
+    config,
+  });
+}
+
+/**
+ * Draws a debug gizmo line for one frame.
+ */
+export function drawGizmoLine(
+  worldId: number,
+  props: {
+    start: [number, number, number];
+    end: [number, number, number];
+    color?: [number, number, number, number];
+  },
+): void {
+  emitIntent(worldId, {
+    type: 'gizmo-draw-line',
+    start: props.start,
+    end: props.end,
+    color: props.color || [1, 1, 1, 1],
+  });
+}
+
+/**
+ * Draws a debug gizmo AABB for one frame.
+ */
+export function drawGizmoAabb(
+  worldId: number,
+  props: {
+    min: [number, number, number];
+    max: [number, number, number];
+    color?: [number, number, number, number];
+  },
+): void {
+  emitIntent(worldId, {
+    type: 'gizmo-draw-aabb',
+    min: props.min,
+    max: props.max,
+    color: props.color || [1, 1, 1, 1],
+  });
+}
+
+/**
+ * Creates a new entity in the specified world.
+ * Returns the entity ID immediately, but the entity is actually created in the next tick.
+ */
+export function createEntity(worldId: number): number {
+  requireInitialized();
+  const entityId = engineState.nextEntityId++;
+
+  emitIntent(worldId, {
+    type: 'create-entity',
+    worldId,
+    entityId,
+  });
+
+  return entityId;
+}
+
+/**
+ * Removes an entity and all its components in the next tick.
+ */
+export function removeEntity(worldId: number, entityId: number): void {
+  emitIntent(worldId, {
+    type: 'remove-entity',
+    entityId,
+  });
+}
+
+/**
+ * Attaches a camera component to an entity via Intent.
+ */
+export function createCamera(
+  worldId: number,
+  entityId: number,
+  props: CameraProps = {},
+): void {
+  emitIntent(worldId, {
+    type: 'attach-camera',
+    entityId,
+    props,
+  });
+}
+
+/**
+ * Attaches a light component to an entity via Intent.
+ */
+export function createLight(
+  worldId: number,
+  entityId: number,
+  props: LightProps = {},
+): void {
+  emitIntent(worldId, {
+    type: 'attach-light',
+    entityId,
+    props,
+  });
+}
+
+/**
+ * Attaches a model component to an entity via Intent.
+ */
+export function createModel(
+  worldId: number,
+  entityId: number,
+  props: ModelProps,
+): void {
+  emitIntent(worldId, {
+    type: 'attach-model',
+    entityId,
+    props,
+  });
+}
+
+/**
+ * Updates an entity's transform via Intent.
+ */
+export function updateTransform(
+  worldId: number,
+  entityId: number,
+  props: TransformProps,
+): void {
+  emitIntent(worldId, {
+    type: 'update-transform',
+    entityId,
+    props,
+  });
+}
+
+/**
+ * Attaches a tag component to an entity via Intent.
+ */
+export function createTag(
+  worldId: number,
+  entityId: number,
+  props: TagProps,
+): void {
+  emitIntent(worldId, {
+    type: 'attach-tag',
+    entityId,
+    props,
+  });
+}
+
+/**
+ * Sets the parent of an entity via Intent.
+ */
+export function setParent(
+  worldId: number,
+  entityId: number,
+  parentId: number | null,
+): void {
+  emitIntent(worldId, {
+    type: 'set-parent',
+    entityId,
+    parentId,
+  });
+}
+
+/**
+ * Resources (Material, Geometry, Texture)
+ */
+
+/**
+ * Creates a material resource and returns its ID.
+ */
+export function createMaterial(worldId: number, props: MaterialProps): number {
+  requireInitialized();
+  const world = getWorldOrThrow(worldId);
+  const resourceId = world.nextCoreId++;
+
+  emitIntent(worldId, {
+    type: 'create-material',
+    resourceId,
+    props,
+  });
+
+  return resourceId;
+}
+
+/**
+ * Creates a geometry resource and returns its ID.
+ */
+export function createGeometry(worldId: number, props: GeometryProps): number {
+  requireInitialized();
+  const world = getWorldOrThrow(worldId);
+  const resourceId = world.nextCoreId++;
+
+  emitIntent(worldId, {
+    type: 'create-geometry',
+    resourceId,
+    props,
+  });
+
+  return resourceId;
+}
+
+/**
+ * Creates a texture resource and returns its ID.
+ */
+export function createTexture(worldId: number, props: TextureProps): number {
+  requireInitialized();
+  const world = getWorldOrThrow(worldId);
+  const resourceId = world.nextCoreId++;
+
+  emitIntent(worldId, {
+    type: 'create-texture',
+    resourceId,
+    props,
+  });
+
+  return resourceId;
+}
+
+/**
+ * Input & Window State Queries
+ */
+
+const WORLD_ENTITY_ID = 0;
+
+/**
+ * Gets the InputState component for a world.
+ * Returns undefined if the system hasn't run yet.
+ */
+function getInputState(worldId: number): InputStateComponent | undefined {
+  requireInitialized();
+  const world = getWorldOrThrow(worldId);
+  const worldStore = world.components.get(WORLD_ENTITY_ID);
+  return worldStore?.get('InputState') as InputStateComponent | undefined;
+}
+
+/**
+ * Gets the WindowState component for a world.
+ * Returns undefined if the system hasn't run yet.
+ */
+function getWindowState(worldId: number): WindowStateComponent | undefined {
+  requireInitialized();
+  const world = getWorldOrThrow(worldId);
+  const worldStore = world.components.get(WORLD_ENTITY_ID);
+  return worldStore?.get('WindowState') as WindowStateComponent | undefined;
+}
+
+/**
+ * Checks if a key is currently pressed.
+ */
+export function isKeyPressed(worldId: number, keyCode: number): boolean {
+  const state = getInputState(worldId);
+  return state?.keysPressed.has(keyCode) ?? false;
+}
+
+/**
+ * Checks if a key was just pressed this frame.
+ */
+export function isKeyJustPressed(worldId: number, keyCode: number): boolean {
+  const state = getInputState(worldId);
+  return state?.keysJustPressed.has(keyCode) ?? false;
+}
+
+/**
+ * Checks if a key was just released this frame.
+ */
+export function isKeyJustReleased(worldId: number, keyCode: number): boolean {
+  const state = getInputState(worldId);
+  return state?.keysJustReleased.has(keyCode) ?? false;
+}
+
+/**
+ * Gets the current mouse position.
+ */
+export function getMousePosition(worldId: number): [number, number] {
+  const state = getInputState(worldId);
+  return state?.mousePosition ?? [0, 0];
+}
+
+/**
+ * Gets the mouse movement delta for this frame.
+ */
+export function getMouseDelta(worldId: number): [number, number] {
+  const state = getInputState(worldId);
+  return state?.mouseDelta ?? [0, 0];
+}
+
+/**
+ * Checks if a mouse button is currently pressed.
+ */
+export function isMouseButtonPressed(worldId: number, button: number): boolean {
+  const state = getInputState(worldId);
+  return state?.mouseButtons.has(button) ?? false;
+}
+
+/**
+ * Checks if a mouse button was just pressed this frame.
+ */
+export function isMouseButtonJustPressed(
+  worldId: number,
+  button: number,
+): boolean {
+  const state = getInputState(worldId);
+  return state?.mouseJustPressed.has(button) ?? false;
+}
+
+/**
+ * Gets the scroll delta for this frame.
+ */
+export function getScrollDelta(worldId: number): [number, number] {
+  const state = getInputState(worldId);
+  return state?.scrollDelta ?? [0, 0];
+}
+
+/**
+ * Gets the current window size.
+ */
+export function getWindowSize(worldId: number): [number, number] {
+  const state = getWindowState(worldId);
+  return state?.size ?? [800, 600];
+}
+
+/**
+ * Gets the current window position.
+ */
+export function getWindowPosition(worldId: number): [number, number] {
+  const state = getWindowState(worldId);
+  return state?.position ?? [0, 0];
+}
+
+/**
+ * Checks if the window is focused.
+ */
+export function isWindowFocused(worldId: number): boolean {
+  const state = getWindowState(worldId);
+  return state?.focused ?? false;
+}
+
+/**
+ * Checks if a close was requested this frame.
+ */
+export function isWindowCloseRequested(worldId: number): boolean {
+  const state = getWindowState(worldId);
+  return state?.closeRequested ?? false;
+}
+
+/**
+ * Checks if the window was resized this frame.
+ */
+export function wasWindowResized(worldId: number): boolean {
+  const state = getWindowState(worldId);
+  return state?.resizedThisFrame ?? false;
+}
+
+/**
+ * Gets the window scale factor (DPI scaling).
+ */
+export function getWindowScaleFactor(worldId: number): number {
+  const state = getWindowState(worldId);
+  return state?.scaleFactor ?? 1.0;
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export { EngineError } from './engine/errors';
+export * from './engine/api';
+export * from './engine/ecs';
+export * as Types from './types';
+export type {
+  BufferResult,
+  EngineTransport,
+  EngineTransportFactory,
+} from '@vulfram/transport-types';

package/src/types/cmds/camera.ts

@@ -0,0 +1,76 @@
+import type { CameraKind } from '../kinds';
+
+/** Viewport value expressed as relative (0..1) or absolute pixels. */
+export interface ViewValue {
+  type: 'relative' | 'absolute';
+  value: number;
+}
+
+/** Viewport definition relative to the window. */
+export interface ViewPosition {
+  anchor: { x: ViewValue; y: ViewValue };
+  size: { width: ViewValue; height: ViewValue };
+}
+
+/** Command payload for creating a camera. */
+export interface CmdCameraCreateArgs {
+  windowId: number;
+  cameraId: number;
+  label?: string;
+  transform: number[]; // Mat4 (16 elements)
+  kind: CameraKind;
+  flags: number;
+  nearFar: [number, number]; // Vec2
+  layerMask: number;
+  order: number;
+  viewPosition?: ViewPosition;
+  orthoScale: number;
+}
+
+/** Result payload for camera create. */
+export interface CmdResultCameraCreate {
+  success: boolean;
+  message: string;
+}
+
+/** Command payload for updating a camera. */
+export interface CmdCameraUpdateArgs {
+  windowId: number;
+  cameraId: number;
+  transform?: number[];
+  kind?: CameraKind;
+  flags?: number;
+  layerMask?: number;
+  order?: number;
+  nearFar?: [number, number];
+  viewPosition?: ViewPosition;
+  orthoScale?: number;
+}
+
+/** Result payload for camera update. */
+export interface CmdResultCameraUpdate {
+  success: boolean;
+  message: string;
+}
+
+/** Command payload for disposing a camera. */
+export interface CmdCameraDisposeArgs {
+  windowId: number;
+  cameraId: number;
+}
+
+/** Result payload for camera dispose. */
+export interface CmdResultCameraDispose {
+  success: boolean;
+  message: string;
+}
+
+/** Command payload for listing cameras. */
+export interface CmdCameraListArgs {}
+
+/** Result payload for camera list. */
+export interface CmdResultCameraList {
+  success: boolean;
+  message: string;
+  content: number[]; // List of camera IDs
+}

package/src/types/cmds/environment.ts

@@ -0,0 +1,45 @@
+import type { SkyboxMode } from '../kinds';
+
+/** MSAA configuration for the renderer. */
+export interface MsaaConfig {
+  enabled: boolean;
+  sampleCount: number;
+}
+
+/** Skybox configuration for the environment. */
+export interface SkyboxConfig {
+  mode: SkyboxMode;
+  intensity: number;
+  rotation: number;
+  tint: [number, number, number];
+  cubemapTextureId?: number | null;
+}
+
+/** Environment configuration for a window. */
+export interface EnvironmentConfig {
+  msaa: MsaaConfig;
+  skybox: SkyboxConfig;
+}
+
+/** Command payload for creating environment settings. */
+export interface CmdEnvironmentCreateArgs {
+  windowId: number;
+  config: EnvironmentConfig;
+}
+
+/** Command payload for updating environment settings. */
+export interface CmdEnvironmentUpdateArgs {
+  windowId: number;
+  config: EnvironmentConfig;
+}
+
+/** Command payload for disposing environment settings. */
+export interface CmdEnvironmentDisposeArgs {
+  windowId: number;
+}
+
+/** Result payload for environment commands. */
+export interface CmdResultEnvironment {
+  success: boolean;
+  message: string;
+}