emoemu 0.1.0

package/src/Emulator/saveState/index.ts

@@ -0,0 +1,155 @@
+import { readFileSync, writeFileSync, existsSync, utimesSync, unlinkSync } from 'fs';
+import { basename, dirname, extname, join } from 'path';
+import type { Core } from '../../core/core';
+import type { Config } from '../../frontend/config';
+import { getSavestatesDirectory, getSavefilesDirectory } from '../../frontend/config';
+import { logger } from '../../utils/logger';
+import { getErrorMessage } from '../../utils/getErrorMessage';
+import { ensureDirectory } from '../../utils/ensureDirectory';
+
+/**
+ * Get the directory for save state files.
+ * Uses ROM directory if savestates_in_content_dir is true (default),
+ * otherwise uses configured savestate_directory or platform default.
+ */
+export const getSavestateDirectory = (config: Config | null, romPath: string): string => {
+  if (!config || config.savestates_in_content_dir !== false) {
+    return dirname(romPath);
+  }
+  return getSavestatesDirectory(config);
+};
+
+/**
+ * Get the path for the save state file.
+ * Format: [rom basename without extension].state.auto
+ */
+export const getStatePath = (config: Config | null, romPath: string): string => {
+  const dir = getSavestateDirectory(config, romPath);
+  const name = basename(romPath, extname(romPath));
+  return join(dir, `${name}.state.auto`);
+};
+
+/**
+ * Get the directory for battery save (.srm) files.
+ * Uses ROM directory if savefiles_in_content_dir is true (default),
+ * otherwise uses configured savefile_directory or platform default.
+ */
+export const getSavefileDirectory = (config: Config | null, romPath: string): string => {
+  if (!config || config.savefiles_in_content_dir !== false) {
+    return dirname(romPath);
+  }
+  return getSavefilesDirectory(config);
+};
+
+/**
+ * Get the path for the battery save (.srm) file.
+ * Uses RetroArch-compatible naming: [rom basename without extension].srm
+ */
+export const getSrmPath = (config: Config | null, romPath: string): string => {
+  const dir = getSavefileDirectory(config, romPath);
+  const name = basename(romPath, extname(romPath));
+  return join(dir, name + '.srm');
+};
+
+/**
+ * Load battery save from .srm file (RetroArch-compatible format).
+ * Raw binary SRAM data, no header.
+ */
+export const loadBatterySave = (core: Core, config: Config | null, romPath: string): void => {
+  if (!core.hasBatterySave()) {
+    return;
+  }
+
+  const srmPath = getSrmPath(config, romPath);
+  if (!existsSync(srmPath)) {
+    return;
+  }
+
+  try {
+    const data = readFileSync(srmPath);
+    core.setBatteryRam(new Uint8Array(data));
+  } catch (err) {
+    logger.warn(`Failed to load battery save: ${srmPath} - ${getErrorMessage(err)}`, 'SaveFile');
+  }
+};
+
+/**
+ * Save battery RAM to .srm file (RetroArch-compatible format).
+ * Raw binary SRAM data, no header.
+ */
+export const saveBatterySave = (core: Core, config: Config | null, romPath: string): void => {
+  if (!core.hasBatterySave()) {
+    return;
+  }
+
+  const batteryRam = core.getBatteryRam();
+  if (!batteryRam) {
+    return;
+  }
+
+  const srmPath = getSrmPath(config, romPath);
+  try {
+    ensureDirectory(dirname(srmPath));
+    writeFileSync(srmPath, Buffer.from(batteryRam));
+    // Force update mtime even if content is identical
+    const now = new Date();
+    utimesSync(srmPath, now, now);
+  } catch (err) {
+    logger.error(`Failed to save battery save: ${srmPath} - ${getErrorMessage(err)}`, 'SaveFile');
+  }
+};
+
+/** Check if a save state exists for the given ROM. */
+export const hasSavedState = (config: Config | null, romPath: string): boolean => {
+  return existsSync(getStatePath(config, romPath));
+};
+
+/**
+ * Save the current state to a .state.auto file.
+ * For libretro cores: raw binary (RetroArch-compatible)
+ */
+export const saveState = (core: Core, config: Config | null, romPath: string): void => {
+  const statePath = getStatePath(config, romPath);
+  try {
+    const state = core.getState();
+    if (!state) {
+      return; // Core doesn't support save states
+    }
+
+    ensureDirectory(dirname(statePath));
+    writeFileSync(statePath, state);
+  } catch (err) {
+    logger.error(`Failed to save state: ${statePath} - ${getErrorMessage(err)}`, 'SaveState');
+  }
+};
+
+/**
+ * Load state from a save state file.
+ * @returns true if state was loaded successfully
+ */
+export const loadStateFromFile = (core: Core, statePath: string): boolean => {
+  if (!existsSync(statePath)) {
+    return false;
+  }
+
+  try {
+    const fileData = readFileSync(statePath);
+    core.setState(fileData);
+    return true;
+  } catch (err) {
+    logger.error(`Failed to load state: ${statePath} - ${getErrorMessage(err)}`, 'SaveState');
+    return false;
+  }
+};
+
+/** Delete the save state file for the given ROM. */
+export const deleteSavedState = (config: Config | null, romPath: string): void => {
+  const statePath = getStatePath(config, romPath);
+  if (existsSync(statePath)) {
+    try {
+      unlinkSync(statePath);
+    } catch (err) {
+      logger.warn(`Failed to delete save state: ${statePath} - ${getErrorMessage(err)}`, 'SaveState');
+    }
+  }
+};

package/src/Emulator/screenshot/index.ts

@@ -0,0 +1,160 @@
+import { writeFileSync } from 'fs';
+import { basename, dirname, extname, join } from 'path';
+import sharp from 'sharp';
+import { VERSION_WITH_DATE as VERSION } from '../../consts';
+import { isRgb15Buffer, type Core, type SystemInfo } from '../../core/core';
+import type { Config } from '../../frontend/config';
+import { getRomTitle } from '../../frontend/romScanner';
+import { getSystemName } from '../../frontend/playlist';
+import { notifyScreenshotSaved } from '../../frontend/notifications';
+import { getThumbnailPath } from '../../utils/paths';
+import { logger } from '../../utils/logger';
+import { getErrorMessage } from '../../utils/getErrorMessage';
+import { rgb15ToRgb24 } from '../../utils/color';
+import { ensureDirectory } from '../../utils/ensureDirectory';
+import { RGB24_BYTES_PER_PIXEL } from '../../rendering';
+import { TWO_DIGIT_YEAR_SLICE_START, ISO_DATETIME_LENGTH } from '../../frontend';
+
+/**
+ * Get the screenshot directory, using config setting or ROM directory as fallback.
+ */
+export const getScreenshotDirectory = (config: Config | null, romPath: string): string => {
+  if (config?.screenshot_directory && config.screenshot_directory.length > 0) {
+    return config.screenshot_directory;
+  }
+  return dirname(romPath);
+};
+
+/**
+ * Generate screenshot filename using RetroArch naming convention.
+ * Format: GameName-YYMMDD-HHMMSS.png
+ */
+export const generateScreenshotFilename = (romPath: string): string => {
+  const romName = basename(romPath, extname(romPath));
+  const now = new Date();
+  const year = String(now.getFullYear()).slice(TWO_DIGIT_YEAR_SLICE_START);
+  const month = String(now.getMonth() + 1).padStart(2, '0');
+  const day = String(now.getDate()).padStart(2, '0');
+  const hours = String(now.getHours()).padStart(2, '0');
+  const minutes = String(now.getMinutes()).padStart(2, '0');
+  const seconds = String(now.getSeconds()).padStart(2, '0');
+  return `${romName}-${year}${month}${day}-${hours}${minutes}${seconds}.png`;
+};
+
+/**
+ * Capture a PNG screenshot asynchronously.
+ * @returns Promise resolving to PNG buffer
+ */
+export const captureScreenshotAsync = async (
+  core: Core,
+  systemInfo: SystemInfo,
+  romPath: string
+): Promise<Buffer | null> => {
+  try {
+    const frameBuffer = core.getFramebuffer();
+    const { width, height, colorSpace } = systemInfo;
+    const pixelCount = width * height;
+
+    // Convert framebuffer to RGB24
+    const rgb = new Uint8Array(pixelCount * RGB24_BYTES_PER_PIXEL);
+
+    if (isRgb15Buffer(colorSpace, frameBuffer)) {
+      // RGB15 (xBBBBBGGGGGRRRRR) - convert to RGB24
+      for (let i = 0; i < pixelCount; i++) {
+        const [r, g, b] = rgb15ToRgb24(frameBuffer[i]);
+        rgb[i * RGB24_BYTES_PER_PIXEL] = r;
+        rgb[i * RGB24_BYTES_PER_PIXEL + 1] = g;
+        rgb[i * RGB24_BYTES_PER_PIXEL + 2] = b;
+      }
+    } else {
+      // RGB24 - copy directly
+      rgb.set(frameBuffer);
+    }
+
+    // Encode to 256-color indexed PNG for smaller file size
+    // Add EXIF metadata with emoemu version, game title, core name, and timestamp
+    // DateTimeOriginal is stored in UTC with OffsetTimeOriginal indicating +00:00
+    const now = new Date();
+    const utcDateTime = now.toISOString().replace('T', ' ').slice(0, ISO_DATETIME_LENGTH).replace(/-/g, ':');
+
+    // Get ROM title from embedded metadata, fallback to filename without extension
+    const romTitle = getRomTitle(romPath) ?? basename(romPath, extname(romPath));
+    const imageDescription = `${romTitle} (${systemInfo.name})`;
+
+    return await sharp(Buffer.from(rgb.buffer), {
+      raw: { width, height, channels: 3 },
+    })
+      .withExif({
+        IFD0: {
+          Software: `emoemu ${VERSION}`,
+          ImageDescription: imageDescription,
+        },
+        IFD2: {
+          DateTimeOriginal: utcDateTime,
+          OffsetTimeOriginal: '+00:00',
+        },
+      })
+      .png({ palette: true, compressionLevel: 9, effort: 10 })
+      .toBuffer();
+  } catch (err) {
+    logger.error(`Failed to capture screenshot: ${getErrorMessage(err)}`, 'Screenshot');
+    return null;
+  }
+};
+
+/**
+ * Take a screenshot and save to file.
+ * Uses RetroArch naming convention: GameName-YYMMDD-HHMMSS.png
+ */
+export const takeScreenshot = (
+  core: Core,
+  systemInfo: SystemInfo,
+  romPath: string,
+  config: Config | null
+): void => {
+  void captureScreenshotAsync(core, systemInfo, romPath).then((pngBuffer) => {
+    if (!pngBuffer) {
+      return;
+    }
+
+    const screenshotDir = getScreenshotDirectory(config, romPath);
+    const filename = generateScreenshotFilename(romPath);
+    const filepath = join(screenshotDir, filename);
+
+    try {
+      ensureDirectory(screenshotDir);
+      writeFileSync(filepath, pngBuffer);
+      notifyScreenshotSaved(filename);
+    } catch (err) {
+      logger.error(`Failed to save screenshot: ${filepath} - ${getErrorMessage(err)}`, 'Screenshot');
+    }
+  });
+};
+
+/**
+ * Save a screenshot as a RetroArch-compatible thumbnail.
+ * Currently saves as 'snap' type (in-game screenshot) in Named_Snaps directory.
+ */
+export const saveThumbnailScreenshot = async (
+  core: Core,
+  systemInfo: SystemInfo,
+  romPath: string
+): Promise<void> => {
+  const romExt = extname(romPath);
+  const systemName = getSystemName(romExt, systemInfo.id);
+  const romTitle = getRomTitle(romPath) ?? basename(romPath, extname(romPath));
+  const thumbnailPath = getThumbnailPath(systemName, romTitle, 'snap');
+  const thumbnailDir = dirname(thumbnailPath);
+
+  try {
+    const screenshot = await captureScreenshotAsync(core, systemInfo, romPath);
+    if (!screenshot) {
+      return;
+    }
+
+    ensureDirectory(thumbnailDir);
+    writeFileSync(thumbnailPath, screenshot);
+  } catch {
+    // Silently ignore thumbnail errors - don't disrupt save state operation
+  }
+};

package/src/Emulator/terminalDimensions/index.ts

@@ -0,0 +1,79 @@
+import { logger } from '../../utils/logger';
+import { getTerminalDimensions } from '../../utils/terminal';
+import { DEFAULT_SOURCE_WIDTH, DEFAULT_SOURCE_HEIGHT } from '../../rendering';
+import { ASPECT_RATIO_DECIMALS } from '../../frontend';
+
+/**
+ * Calculate optimal dimensions for terminal/ASCII/emoji rendering.
+ * sourceWidth/sourceHeight: core framebuffer dimensions
+ * pixelAspectRatio: PAR for the core (e.g., 8/7 for NES, 1.0 for GBC)
+ */
+export const calculateTerminalDimensions = (
+  mode: 'terminal' | 'ascii' | 'emoji',
+  sourceWidth: number = DEFAULT_SOURCE_WIDTH,
+  sourceHeight: number = DEFAULT_SOURCE_HEIGHT,
+  pixelAspectRatio: number = 1.0
+): { width: number; height: number } => {
+  const { width: termCols, height: termRows } = getTerminalDimensions();
+
+  // Leave 2 rows for status line
+  const availableRows = termRows - 2;
+
+  // Calculate display aspect ratio from source dimensions and PAR
+  // displayAspect = (sourceWidth * PAR) / sourceHeight
+  const displayAspect = (sourceWidth * pixelAspectRatio) / sourceHeight;
+
+  // Terminal cells are roughly 1:2 (width:height), so we multiply by 2 below
+  // to compensate when calculating character columns from pixel dimensions
+
+  if (mode === 'emoji') {
+    // Emoji: 1 emoji = 1 pixel, each emoji is 2 terminal columns wide
+    // Emojis appear roughly square (2 cols × 1 row ≈ square due to cell aspect)
+    // width / height = displayAspect
+    let height = availableRows;
+    let width = Math.floor(height * displayAspect);
+    const displayCols = width * 2; // Actual terminal columns needed
+
+    if (displayCols > termCols) {
+      width = Math.floor(termCols / 2);
+      height = Math.floor(width / displayAspect);
+    }
+
+    return { width, height };
+  } else if (mode === 'ascii') {
+    // ASCII: 1 char = 1 pixel
+    // To maintain display aspect, account for cell aspect ratio
+    // displayAspect = (cols * cellWidth) / (rows * cellHeight)
+    // displayAspect = cols / (rows * 2) => cols = rows * 2 * displayAspect
+    let height = availableRows;
+    let width = Math.floor(height * 2 * displayAspect);
+
+    if (width > termCols) {
+      width = termCols;
+      height = Math.floor(width / (2 * displayAspect));
+    }
+
+    return { width, height };
+  } else {
+    // Terminal half-block mode: 1 char = 1x2 pixels
+    // Each half-block character covers 2 vertical pixels
+    // displayAspect = (cols * cellWidth) / ((rows * 2) * cellHeight)
+    // With cellAspect = 0.5: displayAspect = cols / (rows * 4)
+    // But half-blocks double vertical resolution: cols = rows * 2 * displayAspect
+    let height = availableRows;
+    let width = Math.floor(height * 2 * displayAspect);
+
+    if (width > termCols) {
+      width = termCols;
+      height = Math.floor(width / (2 * displayAspect));
+    }
+
+    logger.debug(
+      `Terminal dims: ${width}x${height} (term: ${termCols}x${termRows}, ` +
+      `source: ${sourceWidth}x${sourceHeight}, aspect: ${displayAspect.toFixed(ASPECT_RATIO_DECIMALS)})`,
+      'Render'
+    );
+
+    return { width, height };
+  }
+};

package/src/Emulator/types.ts

@@ -0,0 +1,83 @@
+import type { CoreFactory } from '../frontend/coreRegistry';
+import type { Config } from '../frontend/config';
+import type { SettingsManager } from '../frontend/SettingsManager';
+
+// Re-export RenderMode from SettingsManager for external consumers
+export type { RenderMode } from '../frontend/SettingsManager';
+
+// Post-processing mode type
+export type PostProcessingMode = 'off' | 'custom' | 'crt';
+
+// Effect values structure
+export interface EffectValues {
+  gamma: number;
+  scanlines: number;
+  saturation: number;
+  brightness: number;
+  contrast: number;
+  vignette: number;
+  bloom: number;
+  bloomThreshold: number;
+  ntsc: number;
+  curvature: number;
+  chromaticAberration: number;
+}
+
+// Common renderer interface
+export interface Renderer {
+  renderRgb15(frameBuffer: Uint16Array): string;  // For RGB15 cores (GBC, SNES)
+  renderRgb24(frameBuffer: Uint8Array): string;   // For RGB24 cores (libretro)
+  clearScreen(): string;
+  hideCursor(): string;
+  showCursor(): string;
+  getStatusRow(): number;
+  moveCursorToRow(row: number): string;
+  setDimensions?(width: number, height: number): void;
+  destroy?(): void;  // Cleanup resources (native window, etc.)
+  isWindowBased?: boolean;  // True for window-based renderers (native)
+  shouldClose?(): boolean;  // Check if window close was requested (native)
+}
+
+export interface EmulatorOptions {
+  romPath: string;
+  coreFactory: CoreFactory;  // Core factory for creating the emulator core
+  width?: number;
+  height?: number;
+  colorEnabled?: boolean;
+  renderMode?: import('../frontend/SettingsManager').RenderMode;
+  scale?: number;  // For Kitty renderer
+  enableGamepad?: boolean;  // Enable gamepad/controller support
+  enableAudio?: boolean;  // Enable audio output (default: true)
+  startMuted?: boolean;  // Start with audio muted (default: false)
+  enableSaveState?: boolean;  // Enable save state loading/saving (default: true)
+  enableBatterySave?: boolean;  // Enable battery save loading/saving (default: true)
+  showStatusBar?: boolean;  // Show status bar (default: true)
+  fpsLimit?: number;  // Override FPS limit (0 = uncapped, undefined = core native)
+  enableDiffRendering?: boolean;  // Enable diff-based rendering optimization (default: true)
+  noRender?: boolean;  // Disable video rendering output (for debugging, default: false)
+  frameLimit?: number;  // Limit rendering to N fps (0=off/unlimited, default: 0)
+  pngCompressionLevel?: number;  // PNG compression level 1-9 for Kitty mode (default: 1)
+  gamma?: number;  // Gamma correction for Kitty mode (default: 1.0, CRT-like: 1.1-1.4)
+  scanlines?: number;  // Scanline intensity for Kitty mode (default: 0.0 = disabled, 0.2-0.4 = subtle)
+  saturation?: number;  // Color saturation for Kitty mode (default: 1.0, CRT-like: 1.1-1.3)
+  brightness?: number;  // Brightness multiplier for Kitty mode (default: 1.0)
+  contrast?: number;  // Contrast multiplier for Kitty mode (default: 1.0)
+  vignette?: number;  // Vignette intensity for Kitty mode (default: 0.0 = disabled)
+  bloom?: number;  // Bloom/glow intensity for Kitty mode (default: 0.0 = disabled)
+  bloomThreshold?: number;  // Brightness threshold for bloom (default: 0.6)
+  ntsc?: number;  // NTSC artifact intensity for Kitty mode (default: 0.0 = disabled)
+  curvature?: number;  // CRT curvature for Kitty mode (default: 0.0 = disabled)
+  chromaticAberration?: number;  // Chromatic aberration for Kitty mode (default: 0.0 = disabled)
+  hasUserEffects?: boolean;  // Whether user explicitly specified post-processing effects (default: false)
+  config?: Config;  // Current config for saving preference changes
+  configPath?: string;  // Path to config file for saving
+  settingsManager?: SettingsManager;  // Centralized settings manager (if provided, handles settings sync)
+  // Netplay options
+  netplayHost?: boolean;  // Start as netplay host/server
+  netplayConnect?: string;  // Connect to netplay server (hostname or hostname:port)
+  netplayPort?: number;  // Netplay port (default: 55435)
+  netplayPassword?: string;  // Netplay password
+  netplaySpectate?: boolean;  // Join as spectator
+  netplayNickname?: string;  // Player nickname
+  netplayInputDelay?: number;  // Input delay frames (0-16, default: 0)
+}

package/src/cli/commands/consts.ts

@@ -0,0 +1,10 @@
+/** Width to clear for progress line updates */
+export const LINE_CLEAR_WIDTH = 60;
+/** Percentage multiplier */
+export const PERCENT_MULTIPLIER = 100;
+/** Bytes per kilobyte */
+export const BYTES_PER_KB = 1024;
+/** Space reserved for percentage suffix like " (XX%)" */
+export const PERCENT_SUFFIX_WIDTH = 10;
+/** Length of ellipsis "..." */
+export const ELLIPSIS_LENGTH = 3;