@caperjs/core 0.1.0

package/src/ui/index.ts

@@ -0,0 +1,8 @@
+export * from './Button';
+export * from './FlexContainer';
+export * from './Input';
+export * from './Joystick';
+export * from './Popup';
+export * from './Toast';
+export * from './Toaster';
+export * from './UICanvas';

package/src/utils/array.ts

@@ -0,0 +1,24 @@
+import { intBetween } from './random';
+
+/**
+ * Shuffle an array.
+ * @param array
+ */
+export function shuffle<T>(array: T[]): void {
+  let temp: T;
+  let index: number;
+  for (let i = 0; i < array.length; ++i) {
+    index = intBetween(0, array.length);
+    temp = array[i];
+    array[i] = array[index];
+    array[index] = temp;
+  }
+}
+
+/**
+ * Get a random array element.
+ * @param array
+ */
+export function getRandomElement<T>(array: T[]): T {
+  return array[intBetween(0, array.length)];
+}

package/src/utils/bind.ts

@@ -0,0 +1,79 @@
+type MethodNames = {
+  [key: string]: any;
+};
+
+/**
+ * Binds the provided methods to the provided instance.
+ * @param instance - The instance to which the methods should be bound.
+ * @param methodNames - The names of the methods to bind.
+ */
+export function bindMethods(instance: unknown, ...methodNames: string[]) {
+  methodNames.forEach((methodName) => {
+    const method = (instance as MethodNames)[methodName];
+    if (typeof method === 'function') {
+      (instance as MethodNames)[methodName] = method.bind(instance);
+    }
+  });
+}
+
+/**
+ * Retrieves the names of all methods in an instance's prototype chain.
+ * @param instance - The instance from which to retrieve method names.
+ * @param excludePrefixes - An array of prefixes to exclude from the method names.
+ * @param excludeMethodNames - An array of method names to exclude.
+ * @returns An array of method names.
+ */
+function getInstanceMethodNames(
+  instance: any,
+  excludePrefixes: string[] = [],
+  excludeMethodNames: string[] = [],
+): string[] {
+  let prototype = Object.getPrototypeOf(instance);
+  const methodNames: string[] = [];
+
+  while (prototype) {
+    const filteredMethodNames = Object.getOwnPropertyNames(prototype).filter((propertyName) => {
+      const ownDescriptor = Object.getOwnPropertyDescriptor(prototype, propertyName);
+      return (
+        typeof ownDescriptor?.value === 'function' &&
+        propertyName !== 'constructor' &&
+        !excludePrefixes.some((prefix) => propertyName.startsWith(prefix)) &&
+        !excludeMethodNames.includes(propertyName)
+      );
+    });
+
+    methodNames.push(...filteredMethodNames);
+
+    if (prototype === Object.prototype || Object.prototype.hasOwnProperty.call(prototype.constructor, '__caper_method_binding_root')) {
+      break;
+    }
+
+    prototype = Object.getPrototypeOf(prototype);
+  }
+
+  return methodNames;
+}
+
+/**
+ * Binds all methods of an instance to the instance.
+ * @param instance - The instance to which the methods should be bound.
+ * @param excludePrefixes - An array of prefixes to exclude from the method names.
+ * @param excludeMethodNames - An array of method names to exclude.
+ */
+export function bindAllMethods(instance: any, excludePrefixes: string[] = [], excludeMethodNames: string[] = []) {
+  getInstanceMethodNames(instance, excludePrefixes, excludeMethodNames).forEach((methodName) => {
+    instance[methodName] = instance[methodName].bind(instance);
+  });
+}
+
+/**
+ * Checks if a method exists on an object and, if it does, invokes it with the provided arguments.
+ * @param obj - The object on which to check for the method.
+ * @param methodName - The name of the method to check for and invoke.
+ * @param methodArgs - The arguments to pass to the method.
+ */
+export function checkAndInvokeMethod(obj: any, methodName: string, ...methodArgs: any[]): void {
+  if (typeof obj[methodName] === 'function') {
+    obj[methodName](...methodArgs);
+  }
+}

package/src/utils/canvas.ts

@@ -0,0 +1,26 @@
+export function destroyCanvas(canvas: HTMLCanvasElement | OffscreenCanvas) {
+  const gl = canvas.getContext('webgl');
+  if (gl) {
+    const extension = gl.getExtension('WEBGL_lose_context');
+    if (extension) {
+      extension.loseContext();
+    }
+  }
+  // If you are using a 2D context, there's no direct resource release method,
+  // but you should ensure all operations are complete before nullifying the canvas
+  const ctx = canvas.getContext('2d');
+  if (ctx) {
+    // Perform any necessary cleanup tasks for 2D context
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+  }
+  if (!(canvas instanceof OffscreenCanvas)) {
+    if (canvas.parentNode) {
+      canvas.parentNode.removeChild(canvas);
+    }
+  }
+  canvas.width = 0;
+  canvas.height = 0;
+
+  // @ts-expect-error canvas can't be null;
+  canvas = null;
+}

package/src/utils/color.ts

@@ -0,0 +1,126 @@
+export function toHex(color: number): string {
+  return `#${color.toString(16)}`;
+}
+
+// return a uint color from a hex string
+export function toRgb(hex: string): number {
+  return parseInt(hex.replace(/^#/, ''), 16);
+}
+
+export class Color {
+  public static readonly WHITE: Color = new Color(255, 255, 255);
+  public static readonly BLACK: Color = new Color(0, 0, 0);
+  public static readonly GREY: Color = new Color(127, 127, 127);
+  public static readonly RED: Color = new Color(255, 0, 0);
+  public static readonly GREEN: Color = new Color(0, 255, 0);
+  public static readonly BLUE: Color = new Color(0, 0, 255);
+  public static readonly YELLOW: Color = new Color(255, 255, 0);
+  public static readonly MAGENTA: Color = new Color(255, 0, 255);
+  public static readonly CYAN: Color = new Color(0, 255, 255);
+
+  public r: number;
+  public g: number;
+  public b: number;
+
+  /**
+   * A Color reresented by a red, green and blue component.
+   * @param r The red component of the Color OR the full Color in HEX.
+   * @param g The green component of the Color.
+   * @param b The blue component of the Color.
+   */
+  constructor(r?: number, g?: number, b?: number) {
+    if (r !== undefined && g === undefined) {
+      // tslint:disable-next-line no-bitwise
+      this.r = (r & (255 << 16)) >> 16;
+      // tslint:disable-next-line no-bitwise
+      this.g = (r & (255 << 8)) >> 8;
+      // tslint:disable-next-line no-bitwise
+      this.b = r & 255;
+    } else {
+      this.r = r || 0;
+      this.g = g || 0;
+      this.b = b || 0;
+    }
+  }
+
+  /**
+   * Creates a random Color.
+   * @returns The new Color.
+   */
+  public static random(): Color {
+    return new Color(Math.random() * 255, Math.random() * 255, Math.random() * 255);
+  }
+
+  /**
+   * Converts the rgb values passed in to hex.
+   * @param r The red component to convert.
+   * @param g The green component to convert.
+   * @param b The blue component to convert.
+   * @returns The hex value.
+   */
+  public static rgbToHex(r: number, g: number, b: number): number {
+    // tslint:disable-next-line no-bitwise
+    return (r << 16) | (g << 8) | b;
+  }
+
+  public static rgbToHexString(pNumber: number): string {
+    let hex = Number(pNumber).toString(16);
+    if (hex.length < 2) {
+      hex = '0' + hex;
+    }
+
+    return hex;
+  }
+
+  public static rgbToFullHexString(r: number, g: number, b: number): string {
+    const rStr: string = Color.rgbToHexString(r);
+    const gStr: string = Color.rgbToHexString(g);
+    const bStr: string = Color.rgbToHexString(b);
+
+    return rStr + gStr + bStr;
+  }
+
+  /**
+   * Creates a new Color that is linearly interpolated from  pA to  b .
+   * @param pA The start Color.
+   * @param b The end Color.
+   * @param pPerc The percentage on the path from  pA to  b .
+   * @returns The new Color.
+   */
+  public static lerp(pA: Color, b: Color, pPerc: number): Color {
+    return new Color(pA.r + pPerc * (b.r - pA.r), pA.g + pPerc * (b.g - pA.g), pA.b + pPerc * (b.b - pA.b));
+  }
+
+  /**
+   * Creates a new hex Color that is linearly interpolated from  pA to  b .
+   * @param pA The first Color hex.
+   * @param b The second Color hex.
+   * @param pPerc The percentage along the path from  pA to  b .
+   * @returns The new hex Color.
+   */
+  public static lerpHex(pA: number, b: number, pPerc: number): number {
+    const colorA: Color = new Color(pA);
+    const colorB: Color = new Color(b);
+    return Color.lerp(colorA, colorB, pPerc).toHex();
+  }
+
+  /**
+   * Convert this Color to hex.
+   * @returns The Color in hex format.
+   */
+  public toHex(): number {
+    return Color.rgbToHex(this.r, this.g, this.b);
+  }
+
+  public toHexString(): string {
+    return Color.rgbToFullHexString(this.r, this.g, this.b);
+  }
+
+  /**
+   * Converts the Color components to the 0...1 range.
+   * @returns The new Color.
+   */
+  public toWebGL(): number[] {
+    return [this.r / 255, this.g / 255, this.b / 255];
+  }
+}

package/src/utils/console/Logger.ts

@@ -0,0 +1,86 @@
+import { isDev } from '../env';
+import { capitalize } from '../string';
+
+const colors = {
+  log: 'background: #74b64c; color: black;',
+  warn: 'background: yellow; color: black;',
+  error: 'background: red; color: white;',
+};
+const lifecycleColor = 'background: #1f2937; color: #74b64c;';
+
+export type LoggerMode = 'development' | 'default' | 'disabled';
+
+export class Logger {
+  private static _instance: Logger | null = null;
+
+  private constructor(mode?: LoggerMode) {
+    Logger._instance = this;
+    Logger.mode = mode !== undefined ? mode : isDev ? 'development' : 'default';
+    // check if mode is one of the valid modes
+    if (!['development', 'default', 'disabled'].includes(Logger.mode)) {
+      Logger.mode = 'default';
+    }
+  }
+
+  private static _mode: LoggerMode = 'disabled';
+
+  static get mode(): LoggerMode {
+    return Logger._mode;
+  }
+
+  static set mode(mode: LoggerMode) {
+    Logger._mode = mode;
+  }
+
+  public static initialize(mode?: LoggerMode) {
+    if (Logger._instance) {
+      throw new Error('Logger has already been instantiated.');
+    }
+    Logger._instance = new Logger(mode);
+  }
+
+  public static log(...args: any) {
+    Logger.trace('log', ...args);
+  }
+
+  public static warn(...args: any) {
+    Logger.trace('warn', ...args);
+  }
+
+  public static error(...args: any) {
+    Logger.trace('error', ...args);
+  }
+
+  public static lifecycle(subject: string, phase: 'init' | 'destroy' = 'init', ...args: any[]) {
+    if (Logger.mode === 'disabled') {
+      return;
+    }
+
+    const message = `${subject} ${phase}`;
+
+    if (Logger.mode === 'default') {
+      return console.log(`%c ${capitalize(phase)} `, lifecycleColor, message, ...args);
+    }
+
+    console.groupCollapsed(`%c ${capitalize(phase)} `, lifecycleColor, message, ...args);
+    console.trace(`%c Stack `, lifecycleColor);
+    console.groupEnd();
+  }
+
+  public static trace(type: 'log' | 'warn' | 'error' = 'log', ...args: any[]) {
+    if (Logger.mode === 'disabled') {
+      return;
+    }
+    if (type === 'error') {
+      // Never collapse errors: console.error keeps them visible and renders
+      // Error objects with proper source-mapped stacks.
+      return console.error(`%c ${capitalize(type)} `, colors[type], ...args);
+    }
+    if (Logger.mode === 'default') {
+      return console.log(`%c ${capitalize(type)} `, colors[type], ...args);
+    }
+    console.groupCollapsed(`%c ${capitalize(type)} `, colors[type], ...args);
+    console.trace(`%c Stack `, colors[type]);
+    console.groupEnd();
+  }
+}

package/src/utils/console/index.ts

@@ -0,0 +1 @@
+export * from './Logger';

package/src/utils/debug.ts

@@ -0,0 +1,69 @@
+import { Graphics, Text } from 'pixi.js';
+
+// --- Color palette ---
+export const DebugColors = {
+  bounds: 0x00ffff, // cyan — container bounds
+  innerBounds: 0x00ff00, // green — content/child bounds
+  outerBounds: 0xff0000, // red — outer/padding bounds
+  direction: 0xffff00, // yellow — flow direction indicators
+  gap: 0xff00ff, // magenta — gap/spacing fills
+  region: 0x0078ff, // blue — grid regions
+} as const;
+
+export const DebugAlpha = {
+  stroke: 0.6,
+  fill: 0.1,
+  fillActive: 0.2,
+  crosshair: 0.5,
+} as const;
+
+/**
+ * Creates a Graphics object pre-configured for debug overlays.
+ * Non-interactive, excluded from layout, labeled for identification.
+ */
+export function createDebugGraphics(label?: string): Graphics {
+  const g = new Graphics();
+  g.eventMode = 'none';
+  g.interactiveChildren = false;
+  g.layout = false;
+  g.label = label ?? 'DebugGraphics';
+  return g;
+}
+
+/**
+ * Creates a small monospace Text label for debug overlays.
+ * Dark stroke ensures readability over any background.
+ */
+export function createDebugLabel(text: string, color: number = DebugColors.bounds): Text {
+  const label = new Text({
+    text,
+    style: {
+      fontFamily: 'monospace',
+      fontSize: 10,
+      fill: color,
+      stroke: { color: 0x000000, width: 2 },
+    },
+  });
+  label.eventMode = 'none';
+  label.layout = false;
+  label.label = 'DebugLabel';
+  return label;
+}
+
+// --- Registry ---
+// Tracks active debug items. A future DebugPanel can iterate
+// getDebugRegistry() to render a color → label legend.
+type DebugEntry = { label: string; color: number };
+const _registry = new Map<string, DebugEntry>();
+
+export function registerDebug(id: string, label: string, color: number): void {
+  _registry.set(id, { label, color });
+}
+
+export function unregisterDebug(id: string): void {
+  _registry.delete(id);
+}
+
+export function getDebugRegistry(): ReadonlyMap<string, DebugEntry> {
+  return _registry;
+}

package/src/utils/define.ts

@@ -0,0 +1,120 @@
+import type { SceneAssets, SceneDebug, ScenePlugins } from '../display/Scene';
+import type { AppTypeOverrides } from './types';
+
+type AppPluginId = AppTypeOverrides['Plugins'];
+
+/**
+ * Runtime-free helpers that give scene/plugin/popup/entity config files
+ * strong type inference without forcing users to extend base classes or
+ * hand-type every file-level export.
+ *
+ * They are all typed identity functions (`(config) => config`), following
+ * the Vite / Rollup / Playwright `defineConfig` pattern. No runtime cost:
+ * the vite-plugin-caper-config scanner reads the call's object
+ * argument via AST just like it reads individual `export const` forms.
+ *
+ * Example:
+ *
+ *   // src/scenes/MenuScene.ts
+ *   import { defineScene, Scene } from '@caperjs/core';
+ *   export const scene = defineScene({
+ *     id: 'menu',
+ *     assets: { preload: { bundles: ['menu'] } },
+ *     plugins: ['google-analytics'],
+ *   });
+ *   export default class MenuScene extends Scene { ... }
+ */
+
+/**
+ * Scene metadata accepted by `defineScene`. Mirrors the runtime
+ * `SceneConfig` in `display/Scene.ts` — reuses the canonical `SceneAssets`
+ * / `ScenePlugins` / `SceneDebug` types so there's one source of truth.
+ *
+ * `id` is required here (unlike the runtime `SceneConfig` where it's
+ * optional, because the scene class itself may carry the id).
+ */
+export interface SceneConfigInput {
+  /** Unique scene ID used in `app.scenes.loadScene()`. */
+  id: string;
+  /** Defaults to `true`. Set `false` to hide from discovery without deleting the file. */
+  active?: boolean;
+  /** Defaults to `true` (code-split). Set `false` to force a static import. */
+  dynamic?: boolean;
+  /**
+   * Asset load configuration. Uses the canonical `SceneAssets` shape:
+   *
+   *   { preload: { bundles: [...] }, background: { bundles: [...] }, autoUnload: true }
+   */
+  assets?: SceneAssets;
+  /** Plugin IDs this scene requires. Loaded lazily on scene load. */
+  plugins?: ScenePlugins;
+  /** Labels used by the debug UI scene picker. */
+  debug?: SceneDebug;
+}
+
+export interface PluginConfigInput {
+  /** Unique plugin ID used in `app.getPlugin(id)`. */
+  id: string;
+  /** Defaults to `true`. Set `false` to hide from discovery without deleting the file. */
+  active?: boolean;
+  /** Defaults to `true` (code-split). Set `false` to force a static import. */
+  dynamic?: boolean;
+  /**
+   * Plugin IDs that must be initialized before this one. The framework
+   * topologically sorts plugins by `requires` at bootstrap, so the order
+   * in `caper.config.ts` doesn't matter — required deps will always
+   * `initialize()` (and `postInitialize()`) before any plugin that
+   * requires them.
+   *
+   * Bootstrap fails loudly if a required plugin id isn't registered in
+   * `caper.config.ts plugins[]`, or if there's a dependency cycle. The
+   * error message includes the fix.
+   *
+   * Build-time validation also checks `requires` against discovered
+   * plugin IDs and warns on typos before you ever run the app.
+   */
+  requires?: AppPluginId[];
+}
+
+export interface PopupConfigInput {
+  /** Unique popup ID used in `app.popups.show(id)`. */
+  id: string;
+  active?: boolean;
+  dynamic?: boolean;
+}
+
+export interface EntityConfigInput {
+  /** Unique entity ID used in `app.entities.create(id)`. */
+  id: string;
+  active?: boolean;
+  dynamic?: boolean;
+}
+
+export interface UIConfigInput {
+  /** Unique UI element ID used in `this.add.ui(id)`. */
+  id: string;
+  /** Defaults to `true`. Set `false` to hide from discovery without deleting the file. */
+  active?: boolean;
+  /** Defaults to `false` (static import). Set `true` to code-split. */
+  dynamic?: boolean;
+}
+
+export function defineScene<T extends SceneConfigInput>(config: T): T {
+  return config;
+}
+
+export function definePlugin<T extends PluginConfigInput>(config: T): T {
+  return config;
+}
+
+export function definePopup<T extends PopupConfigInput>(config: T): T {
+  return config;
+}
+
+export function defineEntity<T extends EntityConfigInput>(config: T): T {
+  return config;
+}
+
+export function defineUI<T extends UIConfigInput>(config: T): T {
+  return config;
+}

package/src/utils/env.ts

@@ -0,0 +1,3 @@
+export const env = process.env.NODE_ENV;
+export const isDev = env === 'development';
+export const isProduction = env === 'production';

package/src/utils/events.ts

@@ -0,0 +1,10 @@
+export enum CaperEvent {
+  REQUIRED_ASSETS_START = 'caper-required-assets-start',
+  REQUIRED_ASSETS_PROGRESS = 'caper-required-assets-progress',
+  REQUIRED_ASSETS_COMPLETE = 'caper-required-assets-complete',
+  ASSETS_START = 'caper-assets-start',
+  ASSETS_PROGRESS = 'caper-assets-progress',
+  ASSETS_COMPLETE = 'caper-assets-complete',
+}
+
+export type CaperProgressEvent = CustomEvent<{ progress: number }>;

package/src/utils/framework.ts

@@ -0,0 +1,45 @@
+import {isPromise} from './promise';
+import {Constructor, ImportListItem, ImportListItemModule} from './types';
+
+/**
+ * Checks if the given value is a class.
+ * @param {any} value The value to check.
+ * @returns {boolean} True if the value is a class, false otherwise.
+ */
+function isClass(value: any): boolean {
+  return typeof value === 'function' && /^class\s/.test(Function.prototype.toString.call(value));
+}
+
+/**
+ * Retrieves the constructor of the module from the given import list item.
+ * If the module is a promise, it waits for it to resolve.
+ * If the module is a class, it returns it directly.
+ * If the module has a named export specified in the item, it returns that.
+ * Otherwise, it returns the default export of the module.
+ * @param {ImportListItem<T>} item The import list item to get the module from.
+ * @returns {Promise<Constructor<T>>} A promise that resolves to the constructor of the module.
+ */
+export async function getDynamicModuleFromImportListItem<T = any>(
+  item: ImportListItem<T>,
+): Promise<ImportListItemModule<T>> {
+  let module;
+  let ctor: ImportListItemModule<T>;
+
+  if (isPromise(item.module)) {
+    module = await item.module;
+    ctor = item?.namedExport ? module[item.namedExport] : module.default;
+  } else if (typeof item.module === 'function') {
+    if (isClass(item.module)) {
+      module = item.module;
+      ctor = module as Constructor<T>;
+    } else {
+      module = await (item.module as () => Promise<any>)();
+      ctor = item?.namedExport ? module[item.namedExport] : module.default;
+    }
+  } else {
+    module = item.module;
+    ctor = module;
+  }
+
+  return ctor;
+}

package/src/utils/index.ts

@@ -0,0 +1,27 @@
+export * from './array';
+export * from './bind';
+export * from './canvas';
+export * from './color';
+export * from './console';
+export * from './debug';
+export * from './define';
+export * from './env';
+export * from './events';
+export * from './framework';
+export * from './map';
+export * from './math';
+export * from './misc';
+export * from './number';
+export * from './object';
+export * from './padding';
+export * from './pixi';
+export * from './platform';
+export * from './point';
+export * from './promise';
+export * from './random';
+export * from './rect';
+export * from './set';
+export * from './string';
+export * from './text';
+export * from './types';
+export * from './web';